Enable Error Handling in .NET Report Engine

The .NET Report Engine API includes a facility for collecting and displaying warnings and errors that occur while it is generating output. This article describes what the verify and error handling features do, with some examples of the warnings and errors they capture.

This article also describes the API calls used to enable error handling, and provides example code based on one of our Catapult C# example command-line applications.

The relevant API calls are the TrackErrors property and GetErrorInfo().

What Does It Do?#

The verify feature provides you with actionable information on non-fatal errors, warnings, and other issues contained within a Report Template that occur when generating output with .NET Report Engine.

Error handling is a Tag property that can be set to catch errors and exceptions that occur in a Tag's query. Depending on the error-handling Tag property setting, otherwise fatal errors can be captured and ignored so output can be completed despite the error. For more details about the error-handling Tag property, see the Out Tag Reference.

Example Warnings and Errors#

Here are some examples of the warnings and errors captured when the verify and error handling features are used:

Data Type Issues

warning: ‘Buchanan’ is String while NUMBER expected: <wr:out select=’SELECT dbo.Emplayees.LastName FROM dbo.Employees’ type=’NUMBER’ nickname='TypeError’ error-handling=‘Ignore type error;lgnore formatting error;Ignore select error;Node must exist’ datasource=’MSSQL’/>

warning: ‘Buchanan’ is String while NUMBER expected: <wrout select=’SELECT dbo.Emplayees.LastName FROM dbo.Employees’ type=‘NUMBER’ nickname='TypeError’ error-handling=‘Ignore type error;lgnore formatting error;Ignore select error;Node must exist’ datasource=’MSSQL’/>

Formatting Issues

warning: format(Buchanan, ) is not allowed: <wr:out select=’SELECT dbo.Employees.LastName FROM dbo.Employees’ type=‘NUMBER' nickname=TypeError’ error-handling= Ignore type error;Ignore formatting error;Iqnore select error;Node must exist’ datasource=’MSSQL’/>

warning: Could not parse: Adam: <wr:out select='/Formats-to-test/Author/Firstname’ type=‘DATE’ format=‘categary-date-type:0-format:m/d/yyyy’; nickname=’FORMAT_PROBLEM' error-handling=‘Ignore formatting error;Ignore select error’ datasource='TestingDatabase'/>

warning: format(Buchanan, ) is not allowed: <wr:out select=’SELECT dbo.Employees.LastName FROM dbo.Employees’ type=’NUMBER’ nickname=’TypeError’ error-handling=’Ignore type error;Ignore formatting error;Iqnore select error,Node must exist’ datasource=’MSSQL’/>

Bad Select Statement

warning: Invalid column name ‘dbo’. Final select: select dbo from dbo.Employees: <wr:out select=‘select dbo from dbo.Employees’ nickname=‘DNE1' error-handling=’Ignore select error’ datasource=‘MSSQL’/>

Node Does Not Exist

error: The tag returned no nodes: <wr:out select='/Formats-to-test/Nada’ nickname=‘Nadal' error-handling='Node must exist’ datasource=’TestingDatabase’/>

error: The tag returned no nodes: <wr:out select='/Formats-to-test/Nada’ nickname=‘Nadal' error-handling='Node must exist’ datasource=TestingDatabase’/>

Node Is Null

warning: The tag is empty: <wr:out select=‘select ShipRegion from dbo.Orders where OrderID=10248’ nickname=‘[ShipRegion]’ error-handling=‘Node must not return NULL’ datasource=‘MSSQL’/>

Verification Issues

warning: Tag uses undefined data source ‘OData’: <wr:set select=‘Employees?$select=Nada&$top=1' var='varName3’ nickname=‘DNE8' error-handling=‘Ignore select error’ datasource='OData’/>

warning: Tag uses undefined data source ‘OData’: <wr:set select=‘Employees?$select=Nada&$top=1' var='varName3’ nickname=‘DNE' error-handling=‘Ignore select error’ datasource='OData'/>

TrackErrors#

TrackErrors is used to enable error handling in your .NET Report Engine application:

/// Enable or disable the error handling and verify features. If they are enabled you can call GetErrorInfo() to
/// get a list of errors encountered during the report generation.
/// By default these features are turned off (disabled).
/// Use a combination of ERROR_HANDLING bits to set a value for the property (see below)
public int TrackErrors{...}

TrackErrors is declared in the net.windward.xmlreport.errorhandling namespace.

TrackErrors Flags#

Here are the values to which the TrackErrors property can be set:

/// The settings for the TrackErrors property.
/// These map to ProcessReportApi.ERROR_HANDLING_ values.
[Flags]
public enum ERROR_HANDLING
{
/// <summary>
/// Handle errors as indicated by a tag properties.
/// </summary>
TRACK_ERRORS = 0x01,

/// <summary>
/// Perform verification during a report generation.
/// </summary>
VERIFY = 0x02,

/// <summary>
/// The bitmask that turns the complete error handling functionality off.
/// </summary>
NONE = 0x00,

/// <summary>
/// The bitmask that turns the complete error handling functionality on.
/// </summary>
ALL = 0x03
}

GetErrorInfo()#

GetErrorInfo() is used to process any warnings and errors that occur while .NET Report Engine is running, after TrackErrors is used to turn on error handling:

/// Get an object containing a set of errors encountered during the report generation. To enable the errors tracking
/// you have to turn this feature on by setting TrackErrors.
/// returns an instance of the ErrorInfo implementation.</returns>
public ErrorInfo GetErrorInfo() {...}

GetErrorInfo() is also declared in the net.windward.xmlreport.errorhandling namespace.

RunReportXml.cs Example#

Here is the source file RunReportXml.cs from our Catapult C# command-line examples, with error handling added and NEW COMMENTS IN ALL CAPS:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using net.windward.api.csharp;
using WindwardReportsDrivers.net.windward.datasource;
using WindwardInterfaces.net.windward.api.csharp;
using System.IO;
using net.windward.xmlreport.errorhandling; // USED FOR ERROR HANDLING                                         

namespace RunReportXml
{
    class RunReportXml
    {
        static void Main(string[] args)
        {
            // Initialize the engine
            Report.Init();

            // Open template file and create output file
            FileStream template = File.OpenRead("../../../Samples/Windward Trucking 2 - Template.docx");
            FileStream output = File.Create("../../../Samples/Xml Report.pdf");

            // Create report process
            Report myReport = new ReportPdf(template, output);
 
            // Open a data object to connect to our xml file
            string url = Path.GetFullPath("../../../Samples/Windward Trucking 2 - Data.xml");
            string xsd = null;
            IReportDataSource data = new SaxonDataSourceImpl(string.Format("Url={0}", url), xsd);

            // TURN ON ERROR HANDLING
            myReport.TrackErrors = (int)Report.ERROR_HANDLING.ALL;
            
            // Run the report process
            myReport.ProcessSetup();
            
            // The second parameter is "" to tell the process that our data is the default data source
            myReport.ProcessData(data, "sax");
            myReport.ProcessComplete();
                                 
            // PROCESS ANY ERRORS
            ErrorInfo errors = myReport.GetErrorInfo();
            if (errors.hasErrors())
            {
                java.util.List list = errors.getErrors();
                for (int i = 0; i < list.size(); ++i)
                    Console.Out.WriteLine(((Issue)list.get(i)).getMessage());
            }            

            // Close out of our template file and output
            data.Close();
            output.Close();
            template.Close();

            // Opens the finished report
            string fullPath = Path.GetFullPath("../../../Samples/Xml Report.pdf");
            System.Diagnostics.Process.Start(fullPath);
        }
    }
}